Serverless FrameworkのStep Functions用プラグインでAWSサービスプロキシを設定してみた

knakayama

2017.08.04

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

はじめに

こんにちは、中山です。

先日積読になっていたAWS Computeのブログを読むという徳の高い行為をしていました。該当のブログは以下です。

Implementing Serverless Manual Approval Steps in AWS Step Functions and Amazon API Gateway

Step FunctionsのアクティビティとAPI Gatewayを組み合わせて手動の承認処理を導入するアーキテクチャについて紹介したものになります。大分前の話になりますが、API GatewayのAWSサービスプロキシにStep Functionsが対応した発表を受けて、具体的なユースケースを紹介してくれたようです。

私は文章を読むだけだとあまり理解が進まないので、新しいことを勉強する際には実際に自分で作ってみるようにしてます。後述しますが、アーキテクチャがサーバレスな形になっていたのでServerless Frameworkで作ってみました。内部的にStep Functionsを使っているので、以前ブログで紹介したhorike37/serverless-step-functionsを使ったのですが、機能がかなりアップデートされていたのでそちらを中心にご紹介したいと思います。

検証環境

Node.js: 8.2.1
Serverless Framework: 1.19.0
serverless-step-functions: 1.1.0

アーキテクチャ

今回作成するアーキテクチャを説明します。先程のブログから構成図を引用します。

まとめると以下のようなフローになります。

API GatewayのAWSサービスプロキシでStep Functionsを呼び出せるようにしておく
CloudWatch Eventsで定期的にLambdaをInvoke
InvokeされたLambdaがStep Functionsのタスクの状態を監視
タスクが存在した場合はInputで渡された情報を元にSESでメール送信
メール本文に記載されたAPI Gatewayのエンドポイントに応じて後続のタスクへ遷移するか選択

この仕組みを利用することで、ステートマシーンの中に手動の承認処理をサーバレスな形で導入することが可能です。全て自動化されたフローにするのはまずいような処理をStep Functionsで行いたい場合に便利なのではないでしょうか。

やってみた

今回作成したリポジトリは以下です。ご自由にお使いください。こちらの主要なコードを元に解説します。

knakayama/serverless-manual-approval
serverless.yml

service: serverless-manual-approval

frameworkVersion: ">=1.19.0 <2.0.0"

custom:
  config: ${file(config.yml)}

provider:
  name: aws
  runtime: nodejs6.10
  stage: ${self:custom.config.stage}
  region: ap-northeast-1
  memorySize: 128
  timeout: 60
  iamRoleStatements:
    - Effect: Allow
      Action: states:GetActivityTask
      Resource: "arn:aws:states:#{AWS::Region}:#{AWS::AccountId}:activity:${self:custom.config.stepFunctions.activityName}"
    - Effect: Allow
      Action: ses:SendEmail
      Resource: "*"

plugins:
  - serverless-pseudo-parameters
  - serverless-step-functions

package:
  individually: true
  exclude:
    - "**"

functions:
  func:
    name: ManualStepActivityWorker
    handler: src/handlers/func/index.handler
    environment:
      ACTIVITY_ARN: "arn:aws:states:#{AWS::Region}:#{AWS::AccountId}:activity:${self:custom.config.stepFunctions.activityName}"
      SERVICE_ENDPOINT:
        Fn::Join: [ "", [ "https://", Ref: "ApiGatewayRestApi", ".execute-api.", Ref: "AWS::Region", ".amazonaws.com/${self:custom.config.stage}" ] ]
    package:
      include:
        - src/handlers/func/*.js
    events:
      - schedule: rate(1 minute)

stepFunctions:
  stateMachines:
    promotionApproval:
      events:
        - http:
            path: fail
            method: GET
        - http:
            path: succeed
            method: GET
      definition:
        Comment: "Employee promotion process!"
        StartAt: ManualApproval
        States:
          ManualApproval:
            Type: Task
            Resource: "arn:aws:states:#{AWS::Region}:#{AWS::AccountId}:activity:${self:custom.config.stepFunctions.activityName}"
            TimeoutSeconds: 3600
            End: true
  activities:
    - ${self:custom.config.stepFunctions.activityName}

resources: ${file(resource.yml)}

46 - 66行目でStep Functionsのステートマシーンとアクティビティを定義しています。さらにこちらがすごいのですが、 events を指定することでAPI GatewayのREST APIリソースなどを作成し、Step FunctionsをAWSサービスプロキシとして設定可能です。Serverless FrameworkはLambdaとひも付ける形でAPI Gatewayを定義することは容易ですが、今回のようにAWSサービスプロキシの設定をする場合は自分でテンプレートを作成しなければならず、少々面倒でした。それが一般的な serverless.yml と同じ形式で設定できるのはかなり便利ですね。今回はタスクを承認するために成功/失敗用のメソッドを作成しました。

resource.yml

---
AWSTemplateFormatVersion: "2010-09-09"
Description: Serverless Manual Approval Stack

Parameters:
  LogGroupRetentionInDays:
    Type: Number
    Default: ${self:custom.config.logGroup.retentionInDays}

Resources:
  FuncLogGroup:
    Type: AWS::Logs::LogGroup
    Properties:
      RetentionInDays:
        Ref: LogGroupRetentionInDays

  ApiGatewayRestApi:
    Type: AWS::ApiGateway::RestApi
    Properties:
      Name: StepFunctionsAPI
  ApiGatewayMethodFailGet:
    Type: AWS::ApiGateway::Method
    Properties:
      Integration:
        Uri:
          Fn::Join: [ "", [ "arn:aws:apigateway:", Ref: "AWS::Region", ":states:action/SendTaskFailure" ] ]
        PassthroughBehavior: WHEN_NO_TEMPLATES
        RequestTemplates:
          application/json: |
            {
               "cause": "Reject link was clicked.",
               "error": "Rejected",
               "taskToken": "$input.params('taskToken')"
            }
      RequestParameters:
        method.request.querystring.taskToken: false
  ApiGatewayMethodSucceedGet:
    Type: AWS::ApiGateway::Method
    Properties:
      Integration:
        Uri:
          Fn::Join: [ "", [ "arn:aws:apigateway:", Ref: "AWS::Region", ":states:action/SendTaskSuccess" ] ]
        PassthroughBehavior: WHEN_NO_TEMPLATES
        RequestTemplates:
          application/json: |
            {
               "output": "\"Approve link was clicked.\"",
               "taskToken": "$input.params('taskToken')"
            }
      RequestParameters:
        method.request.querystring.taskToken: false
  ApigatewayToStepFunctionsRole:
    Type: AWS::IAM::Role
    Properties:
      ManagedPolicyArns:
        - arn:aws:iam::aws:policy/AWSStepFunctionsFullAccess

主に horike37/serverless-step-functions で作成したAPI Gatewayの設定をしています。プラグインのREADMEに記載されているようにある程度 serverless.yml 側でAPI Gatewayの設定が可能ですが、執筆時点(2017/08/04)ではすべてのパラメータに対応しているわけではないようです。そのため、Serverless Frameworkのオーバーライドを利用して、プラグインで定義されたリソースを上書きしています。オーバーライドを軽く説明すると、Serverless Frameworkで作成されるCloudFormationのリソースと同じ名前でリソースを定義することにより、パラメータをカスタマイズできる機能です。今回の場合であれば以下のリソース名になるようなので、同じ名前で設定してあげれば上書きが可能です。

ApiGatewayMethodFailGet
- SendTaskFailure APIを送るためのメソッド
ApiGatewayMethodSucceedGet
- SendTaskSuccessを送るためのメソッド
ApigatewayToStepFunctionsRole
- API GatewayからStep Functionsを操作する際に利用するIAM Role

API Gatewayのメソッドについて少し触れると、 Integration - RequestTemplates と RequestParameters パラメータでtaskTokenをパラメータ形式で処理できるように定義させています。

src/handlers/func/index.js

const AWS = require('aws-sdk');

class Worker {
  constructor(event, context, callback) {
    this.event = event;
    this.context = context;
    this.callback = callback;
    this.stepfunctions = new AWS.StepFunctions();
    this.ses = new AWS.SES({ region: 'us-east-1' });
  }

  getActivityTask() {
    const params = {
      activityArn: process.env.ACTIVITY_ARN,
    };
    return this.stepfunctions.getActivityTask(params).promise();
  }

  sendEmail(data) {
    const input = JSON.parse(data.input);
    const params = {
      Destination: {
        ToAddresses: [
          input.managerEmailAddress,
        ],
      },
      Message: {
        Subject: {
          Data: 'Your Approval Needed for Promotion!',
          Charset: 'UTF-8',
        },
        Body: {
          Html: {
            Data: 'Hi!<br />' +
              `${input.employeeName} has been nominated for promotion!<br />` +
              'Can you please approve:<br />' +
              `${process.env.SERVICE_ENDPOINT}/succeed?taskToken=${encodeURIComponent(data.taskToken)}<br />` +
              'Or reject:<br />' +
              `${process.env.SERVICE_ENDPOINT}/fail?taskToken=${encodeURIComponent(data.taskToken)}`,
            Charset: 'UTF-8',
          },
        },
      },
      Source: input.managerEmailAddress,
      ReplyToAddresses: [
        input.managerEmailAddress,
      ],
    };
    return this.ses.sendEmail(params).promise();
  }

  start() {
    this.getActivityTask()
      .then((data) => {
        console.log(data);
        return this.sendEmail(data);
      })
      .then((data) => {
        console.log(data);
        this.callback(null, data);
      })
      .catch((err) => {
        console.log(err);
        this.callback(err);
      });
  }
}

module.exports.handler = (event, context, callback) => {
  new Worker(event, context, callback).start();
};

AWSのブログに記載されているコードを元に作成しました。やってることは単純です。Step FunctionsのGetActivityTask APIを呼び出してタスクの状態を監視、データを取得できた場合はSESのSendEmail APIでメールを送信しているだけです。

32 - 39行目でメール本文に記載するAPI Gatewayのエンドポイントへのリンクを作成しています。GetActivityTask APIのレスポンスで返されたtaskTokenを含めることにより、API Gatewayからタスクに対してAPIを発行できるようにしています。

9行目でSESのクライアントを設定していますが、東京リージョンにまだ来ていないので北部バージニアリージョンを利用しました。現時点でCloudFormationがSESに未対応ということもあり、SES周りは手動で環境を作成しています。サンドボックス内の場合は送信するメールアドレスに対して事前に承認する必要がある点はご注意ください。

動作確認

いつものようにServerless Frameworkをデプロイしたら動作確認してみます。まずリポジトリのトップディレクトリにある input.json を以下のように修正してください。

input.json

{
  "managerEmailAddress": "<SESからメール送信可能なメールアドレス>",
  "employeeName" : "<適当な名前>"
}

続いてステートマシーンを実行します。以下のコマンドで実行可能です。

$ yarn invoke:stepf

しばらくするとメールアドレスに以下のようなメールが届くと思います。

承認/否認用リンクのどちらかをクリックするとステートマシーンの実行が完了します。

まとめ

いかがだったでしょうか。

horike37/serverless-step-functions を中心にステートマシーンへ手動の承認処理を導入する方法をご紹介しました。一般的にサーバレスアーキテクチャはEC2等のインスタンスを管理せずに済むという点が強調されがちですが、アーキテクチャ全体をコードという形で管理できるという点も魅力の1つです。その際、Serverless Frameworkやそのプラグインを利用することで簡単にコードを定義できるのは便利ですね。引き続きサーバレス分野の動向を追っていきたいと思います。

本エントリがみなさんの参考になれば幸いに思います。